
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<HTML>

<HEAD>
   <TITLE>return_c</TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">
<A name="TOP"></A>

<table style="text-align: left; margin-left: auto; margin-right: auto; width: 800px;"
 border="0" cellpadding="5" cellspacing="2">
  <tbody>
    <tr>
      <td style="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
      <div align="right"> 
      <small><small><a href="index.html">Index Page</a></small></small>
      </div>
      <b>return_c</b> </td>
    </tr>

    <tr>
      <td style="vertical-align: top;">

<small><div align="center">
<A HREF="index.html#A">A</A>&nbsp;
<A HREF="index.html#B">B</A>&nbsp;
<A HREF="index.html#C">C</A>&nbsp;
<A HREF="index.html#D">D</A>&nbsp;
<A HREF="index.html#E">E</A>&nbsp;
<A HREF="index.html#F">F</A>&nbsp;
<A HREF="index.html#G">G</A>&nbsp;
<A HREF="index.html#H">H</A>&nbsp;
<A HREF="index.html#I">I</A>&nbsp;
<A HREF="index.html#J">J</A>&nbsp;
<A HREF="index.html#K">K</A>&nbsp;
<A HREF="index.html#L">L</A>&nbsp;
<A HREF="index.html#M">M</A>&nbsp;
<A HREF="index.html#N">N</A>&nbsp;
<A HREF="index.html#O">O</A>&nbsp;
<A HREF="index.html#P">P</A>&nbsp;
<A HREF="index.html#Q">Q</A>&nbsp;
<A HREF="index.html#R">R</A>&nbsp;
<A HREF="index.html#S">S</A>&nbsp;
<A HREF="index.html#T">T</A>&nbsp;
<A HREF="index.html#U">U</A>&nbsp;
<A HREF="index.html#V">V</A>&nbsp;
<A HREF="index.html#W">W</A>&nbsp;
<A HREF="index.html#X">X</A>&nbsp;
</div></small>
       <br>
       <table style="text-align: left; width: 60%; margin-left: auto; margin-right: auto;"
       border="0" cellspacing="2" cellpadding="2">
        <tbody>
          <tr>
            <td style="width: 50%; text-align: center;">
            <small>
              <a href="#Procedure">Procedure<br></a>
              <a href="#Abstract">Abstract<br></a>
              <a href="#Required_Reading">Required_Reading<br></a>
              <a href="#Keywords">Keywords<br></a>
              <a href="#Brief_I/O">Brief_I/O<br></a>
              <a href="#Detailed_Input">Detailed_Input<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Detailed_Output">Detailed_Output<br></a>
              <a href="#Parameters">Parameters<br></a>
              <a href="#Exceptions">Exceptions<br></a>
              <a href="#Files">Files<br></a>
              <a href="#Particulars">Particulars<br></a>
              <a href="#Examples">Examples<br></a>

              </small>
              </td>
              <td style="vertical-align: top; width: 50%; text-align: center;">
              <small>               <a href="#Restrictions">Restrictions<br></a>
              <a href="#Literature_References">Literature_References<br></a>
              <a href="#Author_and_Institution">Author_and_Institution<br></a>
              <a href="#Version">Version<br></a>
              <a href="#Index_Entries">Index_Entries<br></a>
             </small>
            </td>
          </tr>
        </tbody>
</table>

<h4><a name="Procedure">Procedure</a></h4>
<PRE>
   SpiceBoolean return_c ( void )

</PRE>
<h4><a name="Abstract">Abstract</a></h4>
<PRE>
 
   True if CSPICE routines should return immediately upon entry. 
 </PRE>
<h4><a name="Required_Reading">Required_Reading</a></h4>
<PRE>
 
    <a href="../req/error.html">ERROR</a> 
 </PRE>
<h4><a name="Keywords">Keywords</a></h4>
<PRE>
 
    ERROR 
 

</PRE>
<h4><a name="Brief_I/O">Brief_I/O</a></h4>
<PRE>
 
    VARIABLE  I/O  DESCRIPTION 
    --------  ---  -------------------------------------------------- 
 
    The function returns the value, SPICETRUE, if and only if CSPICE 
    routines should return immediately upon entry. 
 </PRE>
<h4><a name="Detailed_Input">Detailed_Input</a></h4>
<PRE>
 
    None. 
 </PRE>
<h4><a name="Detailed_Output">Detailed_Output</a></h4>
<PRE>
 
    The function returns the value, SPICETRUE, if and only if CSPICE 
    routines should return immediately upon entry.  The criterion 
    for this is that the error response action is set to 
    &quot;RETURN&quot;, and an error condition exists. 
 </PRE>
<h4><a name="Parameters">Parameters</a></h4>
<PRE>
 
   None. 
 </PRE>
<h4><a name="Exceptions">Exceptions</a></h4>
<PRE>
 
    This routine does not detect any errors. 
 
    However, this routine is part of the CSPICE error 
    handling mechanism. 
 </PRE>
<h4><a name="Files">Files</a></h4>
<PRE>
 
    None. 
 </PRE>
<h4><a name="Particulars">Particulars</a></h4>
<PRE>
 
    Please read the &quot;required reading&quot; first! 
 
    This routine can be referenced in non-toolkit code; in 
    fact, its use is encouraged.  Its purpose is to signal 
    to the routine calling it that the caller should 
    return immediately.  The reference to <b>return_c</b> should 
    be the first executable line of the calling program. 
 
    In &quot;RETURN&quot; mode, CSPICE routines 
    that have external references, or that can 
    detect errors, return immediately upon entry when an 
    error condition exists.  They use <b>return_c</b> to determine 
    when these conditions are met.  Non--toolkit routines 
    can do the same. 
 
    Additionally, when an error is signalled in &quot;RETURN&quot; mode, 
    no further errors can be signalled until the error condition 
    is reset by a call to <a href="reset_c.html">reset_c</a>.  Calls to SIGERR simply have 
    no effect.  Therefore, the error messages set in response 
    to the FIRST error that was detected will be saved until 
    <a href="reset_c.html">reset_c</a> is called.  These messages can be retrieved by 
    calls to <a href="getmsg_c.html">getmsg_c</a>. 
 
    There are a number of advantages to using this mechanism. 
    First, the likelihood of an error resulting in crash 
    in a different routine is greatly reduced.  Second, 
    a program does not have to test the error status 
    (using a reference to <a href="failed_c.html">failed_c</a>) after each call to a toolkit 
    routine, but rather can make one test of status at the end 
    of a series of calls.  See &quot;Examples&quot; below. 
 
    See the subroutine <a href="erract_c.html">erract_c</a> for definitions of the error action  
    codes. 
 </PRE>
<h4><a name="Examples">Examples</a></h4>
<PRE>
 
    1.  In this example, we show how to place a reference 
        to <b>return_c</b> in your code: 
 
       /. 
              No executable lines precede this one. 
          
              Test whether to return before doing 
              anything else. 
       ./ 
 
              if ( <b>return_c</b>() )
                 {
                 return;                 
                 }
 
 
              [ rest of code goes here] 
 
                        . 
                        . 
                        . 
 
 
    2.  Here's how one might code a sequence of calls 
        to routines with code that follows the pattern 
        given in example #1 above: 
 
                       . 
                       . 
                       . 
 
              [ code may go here ] 
 
       /. 
              We call routines A, B, and C;  then we 
              test for errors, using the CSPICE error 
              status indicator, <a href="failed_c.html">failed_c</a>: 
       ./ 
 
              A(); 
              B();
              C();
 
              if ( <a href="failed_c.html">failed_c</a>() )
                 {
 
       /. 
                 If we're here, an error occurred.  The 
                 error might have been detected by A, B, C, 
                 or by a routine called by one of them. 
                 Get the explanation of the short error message 
                 and output it using the routine, user_out_c 
                 [user_out_c is a fictitious routine]: 
       ./ 
 
                 <a href="getmsg_c.html">getmsg_c</a> ( &quot;EXPLAIN&quot;, MSG );
 
                 user_out_c ( MSG );
 
                 } 
 
              [ rest of code goes here ] 
 
                         . 
                         . 
                         . 
</PRE>
<h4><a name="Restrictions">Restrictions</a></h4>
<PRE>
 
    This routine has no effect unless the error action is &quot;RETURN&quot;! 
 </PRE>
<h4><a name="Literature_References">Literature_References</a></h4>
<PRE>
 
    None. 
 </PRE>
<h4><a name="Author_and_Institution">Author_and_Institution</a></h4>
<PRE>
 
    N.J. Bachman    (JPL) 
    K.R. Gehringer  (JPL) 
 </PRE>
<h4><a name="Version">Version</a></h4>
<PRE>
 
   -CSPICE Version 1.1.0, 23-JUL-2001 (NJB)
     
       Removed tab characters from source file.

   -CSPICE Version 1.0.0, 08-FEB-1998   (EDW)
</PRE>
<h4><a name="Index_Entries">Index_Entries</a></h4>
<PRE>
 
   immediate return indicator 
 </PRE>
<h4>Link to routine return_c source file <a href='../../../src/cspice/return_c.c'>return_c.c</a> </h4>

      </td>
    </tr>
  </tbody>
</table>

   <pre>Wed Jun  9 13:05:28 2010</pre>

</body>
</html>

